Indicator that user has clicked a picture button, or is holding down a repeating picture button.
The doPictButton event reports that the user has clicked a picture button in the active window. The doPictButton event is also reported if the user holds down a repeating picture button. Repeating picture button’s will produce events as long as: [1] the mouse button is held down, [2] the button does not reach the end of its range, and [3] the mouse pointer stays inside the picture button’s region.
Programming Considerations
``````````````````````````
• If the “automatic value change” option is not on, your application has
to set the picture button’s value by using SetPictButtonVal or
SetPictButtonValSelect.
• If you have created a picture button that is “lock selected” with the
“automatic value change” option off, and you’ve done this to validate
the picture button before proceeding to the next stage, do the
following: validate the button. If it can proceed to the next stage,
use SetPictButtonValSelect to deselect the button and increment its
value, otherwise use SetPictButtonValSelect to deselect the button and
leave its value unchanged.
• If the user clicked a picture button that is functioning like a radio
button, use SelectPictButton to deselect the other picture buttons in
the group.
• This event will never occur when the watch cursor is displayed, since
picture buttons cannot be clicked. The exception is if the
WatchCursorButtons procedure has been used to allow the watch cursor
to click picture buttons.
• Picture buttons with the “repeating events” option turned on may
produce doNothing events if your application calls PollSystem more
frequently than the button changes its value. This will cause no ill
side-effects, but you should be aware of this.
• A doPictButton event is not generated when the user clicks picture
buttons in another application, control panel or desk accessory.
These events are handled automatically.
• A negative button number value indicates that the decrementing half of
a split button was clicked (i.e., “-5” indicates that button 5 is a
The doClickControl event reports that the user has clicked in a custom control. This event must be handled entirely by your application, since only you know how your custom control should behave.
Programming Considerations
``````````````````````````
• This event will never occur when the watch cursor is displayed, since
Indicator that an event has been reported that can’t be processed by Tools Plus.
The doManualEvent event reports that some type of event has occurred which should be processed by your application. This includes seven (7) possible types of events as defined by the Toolbox Event Manager, which are listed below. If your application does not make use of any of these events, it can ignore the doManualEvent event code.
diskEvt The Standard File Package takes care of all disk-inserted
events, so applications using this package can ignore
diskEvt events. If your application is unusual and it
circumvents the Standard File package, your application
will have to handle disk-inserted events itself.
networkEvt Your application needs to respond to network events only
if it is going to be communicating with the AppleTalk
manager. If it is, you should read the appropriate
documentation in chapter 10 Vol. 2 of Inside Macintosh
regarding networks.
driverEvt If your application does not intend to work with device
drivers, it can ignore these events. Otherwise, you
should read the appropriate documentation in Inside
Macintosh regarding device drivers.
app1Evt Application-defined events 1 through 4. These are events
app2Evt whose meaning is defined by your application. If your
app3Evt application does not define custom events, it can ignore
app4Evt these event codes. Note that app4Evt (or osEvt) will
osEvt only be reported if your application does not respond to
Suspend/Resume events. See the SIZE resource for
details. If your application does respond to Suspend/
Resume events, it will receive a doSuspend or doResume
Tools Plus event.
kHighLevel- Your application needs to respond to these events only if
Evt you have defined the SIZE resource to respond to high-
The doMoveWindow event reports that the user has repositioned a window by dragging it by its title bar. Most applications will choose to ignore this event.
Programming Considerations
``````````````````````````
• The dragged window might not be the active window. The user can drag
an inactive window by holding down the Command key before beginning
the drag.
• If part or all of a window is exposed by the drag and needs to be
refreshed, a subsequent call to PollSystem will report a doRefresh
event for this window.
• Your application may call WindowStatus to obtain the window’s new
location in the screen’s global co-ordinates.
• This event will never occur when the watch cursor is displayed, since
the title bar cannot be clicked.
• A doMoveWindow event is not generated when the user drags a desk
The doClickDesk event reports that the user has clicked in the desk top. Most applications will choose to ignore this event, however, it can be used to deselect objects on the active window.
Programming Considerations
``````````````````````````
• This event will never occur when a modal window is active, since
clicks cannot occur outside of the window.
• This event will never occur when the watch cursor is displayed, since
Indicator that user has changed a window’s size and/or location by zooming.
The doZoomWindow event reports that the user has changed a window’s size and/or position by clicking the “zoom box.” This will always occur on the active window. Applications will typically ignore this event, or treat it similarly to the doGrowWindow event.
Programming Considerations
``````````````````````````
• Your application can call the WindowStatus procedure to obtain the
window’s new width and height in pixels, as well as its new location
in the screen’s global co-ordinates.
• The window’s entire contents are erased during the zoom. A subsequent
call to PollSystem will report a doRefresh event for this window.
Responding to the doRefresh event will regenerate the window’s
contents.
• This event will never occur when the watch cursor is displayed, since
the zoom box cannot be clicked.
• A doZoomWindow event is not generated when the user click’s a desk
accessory’s zoom box. The process is handled automatically.
Indicator that your application is about to be suspended.
The doSuspend event reports that your application will be suspended (or become a “background” application) the next time you call PollSystem. This occurs under MultiFinder or System 7 when a desk accessory or other application is launched, or when an inactive window belonging to a desk accessory or another application is activated.
Programming Considerations
``````````````````````````
• If your application is cutting, copying or pasting specialized objects
(i.e. not text that is handled by editing fields), copy this material
The doResume event reports that your application has become the active application. This occurs under MultiFinder or System 7 after your application has become suspended (see the doSuspend event).
Programming Considerations
``````````````````````````
• If your application is cutting, copying or pasting specialized objects
(i.e. not text that is handled by text editing fields), you may want
to check the clipboard to see if it contains the specialized objects
that you can paste, then copy them to your local scrap.
Set the number of ticks (1/60 sec) your application can wait until it receives a doNothing event, and can perform one cycle of its background process. These settings affect only doNothing events.
pascal void SetNullTime (long ForegroundTime; long BackgroundTime);
ForegroundTime is the amount of time (in 1/60 second “ticks”) your application can wait between receiving doNothing events when the application is the active application. You can specify a value from 0 (maximum background processing speed at the expense of other applications) to 15 (four cycles per second).
BackgroundTime is the amount of time (in 1/60 second “ticks”) your application can wait between receiving doNothing events when the application is suspended (i.e. when another application is active under MultiFinder or System 7).
By default, Tools Plus is initialized with ForegroundTime and BackgroundTime set to 0, meaning your application will have maximum performance at the expense of other applications and processes. Normally, applications that do background processing will set ForegroundTime to 1, and BackgroundTime to a higher value, thus slowing down the background processing when your application is suspended. If your application doesn’t do any background processing, use the maxNullTime constant to allow other applications and process the maximum utilization of the processor.
Your application can change the values of ForegroundTime and BackgroundTime at any time. The change will take effect the next time that PollSystem is called.
Also see: WaitAvail.
CONST {Background process scheduling }
maxNullTime = $7FFFFFFF; {Infinite time between doNothing events }
Determine if the Macintosh running your application supports scheduled processing. This determines if SetNullTime’s settings will have any effect.
pascal Boolean WaitAvail(void);
function WaitAvail: BOOLEAN;
This function returns a value of true if scheduled background processing is supported, or false if it is not. If the Macintosh running your application doesn’t support scheduled background processing, then SetNullTime’s settings will have no effect, and your application will receive a doNothing event each time it calls PollSystem when there are no events available. Internally, this routine reports if the WaitNextEvent trap is available to your application.
Discontinue a mouse’s “drag” or multiple clicks in progress.
pascal void ResetMouseClicks(void);
procedure ResetMouseClicks;
The PollSystem function is used to detect single-clicks, double-clicks, and triple-clicks, as well as dragging which occurs between a mouse-down and mouse-up event. In some applications, it may suffice to know that the user pressed the mouse button with the cursor being within a specific region or cursor zone, without concern for the mouse button’s release. Or an application may allow a single-click only, thereby disallowing double or triple clicks.
In such cases, the ResetMouseClicks procedure can be used to tell Tools Plus that sufficient mouse information has been retrieved, and to reset the click and drag mechanism. This reset will clear the current click or drag from PollSystem’s event queue. The next time the mouse button in pressed down, it will be considered to be a first mouse-down of either a single-click, double-click, triple-click, or drag.
See PollSystem for details on how the system responds to mouse events.
Determine if your application has been suspended (i.e. not the active application).
pascal Boolean ApplicationSuspended(void);
function ApplicationSuspended: BOOLEAN;
This function returns a value of true if a desk accessory or another application is active under MultiFinder or System 7). A value of false is returned if your application is active, even though your application may not have any windows open.
When running under MultiFinder or System 7, your application needs to have a SIZE resource with the “AcceptSuspendEvents” bit set to “1.” See the SIZE resource for details.
